<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>
  <HEAD>
    <META http-equiv="Content-Language" content="en-us">
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">

    <TITLE>BSim Feature Visualizer Plugin</TITLE>
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
</HEAD>

<BODY>
   <H1><A name="BSimFeatureVisualizerPlugin"></A> BSim Feature Visualizer Plugin</H1>

     <P>The <B>BSim Feature Visualizer Plugin</B> is used to visualize the 
     <a class="ulink" href="help/topics/BSim/FeatureWeight.html#FunctionFeatures" 
     target="_top">BSim Features</a> of the function at the current address. 
     
   <H2><A name="BSimFeatureTable"></A> The BSim Feature Table</H2>
      
     <P> The features are displayed in the <b>BSim Feature Table</b>. In order to
     explain the columns of the table, we first briefly discuss BSim feature types.</P>
   
   <H3><A name="DATA_FLOW"></A> DATA_FLOW features</H3>
     <P> These features describe data flow into a single "base" varnode.  A neighborhood of the data
     flow graph consisting of the base varnode and all vertices reachable by traversing edges 
     against the direction of flow (through at most 3 pcode ops) is hashed to produce these 
     features.
    
   <H3><A name="CONTROL_FLOW"></A> CONTROL_FLOW features</H3>
     <P> These features describe small neighborhoods of the control flow graph. Each neighborhood 
     is defined by a "base" block. </P>
   
   <H3><A name="COMBINED"></A> COMBINED features</H3>
     <P> These features are generated from a neighborhood in the control flow graph and data flow 
     information into the first "root" pcode op in the block, which must be either a CALL, CALLIND, 
     CALLOTHER, STORE, CBRANCH, BRANCHIND, or RETURN op.  </P>   
      
   <H3><A name="DUAL_FLOW"></A> DUAL_FLOW features</H3>
     <P> These features are formed from two adjacent "root" ops (as defined above) in a single basic
     block.</P> 
     
   <H3><A name="COPY_SIG"></A> COPY_SIG features</H3>
   <P> These features are formed from the "standalone copies" within a basic block.  An example of
   a standalone copy is an assignment of a constant to a global variable with no further dataflow
   within the function.</P>
       
    <H3><A name="TableColumns"></A> Table Columns</H3>
      <P> We now list the columns of the BSim feature table.  Note that some columns only apply to 
      some BSim feature types. If a column does not apply to a given feature it will be blank the in
      corresponding row. </P>
     <ul>
     <li> <b>Sequence Number</b>: 
     (See <a class="ulink" href="help/topics/DecompilePlugin/DecompilerConcepts.html#ConceptPcodeOps" target="_top">here</a> 
     for details on sequence numbers).For DATA_FLOW and COMBINED features, 
     this column contains
     the sequence number of the pcode op associated with the feature.  For DUAL_FLOW features it 
     contains the sequence number of the main pcode op (which is the second op in address order). 
     For CONTROL_FLOW features it contains an artificial sequence number corresponding to the 
     beginning of the associated basic block.</li>
     <li> <b>Address</b>: This column is hidden by default. It contains the address corresponding to
     the sequence number defined above.</li>
     <li> <b>Base Varnode</b>: For DATA_FLOW features, this column shows the corresponding base 
     varnode.  For other feature types it is blank.</li>
     <li> <b>Basic Block Start</b>: For CONTROL_FLOW and COMBINED features this is the start address
     of the basic block corresponding to the feature.  For DATA_FLOW and DUAL_FLOW features it is 
     the start address of the basic block containing the relevant pcode op(s). </li>
     <li> <b>Block Index</b>: This is the block index of the basic block defined above. </li>
     <li> <b>Feature</b>: This is the 32-bit hash corresponding to the feature. </li>
     <li> <b>Feature Type</b>: The feature type of the feature. </li>
     <li> <b>Pcode Op Name</b>: For DATA_FLOW features this is the name of the pcode op defining the
      base varnode.  For COMBINED features it is the root pcode op, and for DUAL_FLOW features it is
      the main pcode op. </li>
     <li> <b> Previous Op Info</b>: For DUAL_FLOW features, this is the Mnemonic and Sequence number
     of the previous pcode op. </li> 
     </ul>
      
   <H2><A name="Visualizing_BSim_Features"></A>  Visualizing BSim Features</H2>
     <P> To visualize a BSim feature, right-click on a row in the BSim Feature Table and select 
     "Highlight and Graph". This action creates a graph showing the regions of the control flow and 
     data flow graphs which correspond to the feature.  Most (but not all) of the data that goes 
     into the hash is depicted in the graph.  The action also highlights some tokens in the 
     decompiler associated with the feature.  Note that if the "Highlight by Row" option is 
     selected then the decompiler highlight is applied automatically whenever the selected
     row changes.
      
   <H3>The Graph</H3>
     <P> Hovering over a vertex or edge in the graph will display a popup listing its attributes. 
     Vertices corresponding to basic blocks are displayed as rectangle whereas vertices 
     corresponding to varnodes and pcode ops are generally drawn as circles (function inputs and 
     constants are drawn as triangles).  Certain COPY, MULTIEQUAL, and INDIRECT ops are colored 
     differently to indicate that they are collapsed during feature generation.  Note that the graph
     can be used to navigate and make selections.
      
   <H3> Decompiler Highlights </H3>
     <P> Certain tokens in the decompiler corresponding to the feature are highlighted in the 
     decompiler.  In general, the highlight show less information than the graph.  For instance, 
     for DATA_FLOW features, only the base varnode, its defining op, and the line containing them 
     are highlighted.  Note that sometimes there will not be a token to highlight, which can result
     from features of temporary varnodes that are not associated with a C language token. Also note 
     that the decompiler performs additional transformations when producing C code which can 
     complicate token highlighting. 
      
   <H3><A name="Removing_Decompiler_Highlights"></A> Removing Decompiler Highlights </H3>
     <P> Click the <IMG src="images/error.png"> in the upper right corner of the table to clear any
     decompiler highlights added by this plugin.  Other decompiler highlights are unaffected. </P>
       
   <H2><A name="Options"></A> Options </H2>
      
     <P> This plugin has several options which can be set in the Tool Options menu. </P>
      
   <H3><A name="Config_File"></A> Database Configuration File</H3>
      
     <P> This file must be a BSim database configuration template.  An "index tuning" parameter is
     read from this file and passed to the decompiler when generating BSim features. See
     <a class="ulink" href="help/topics/BSim/DatabaseConfiguration.html#CreateDatabase" target="_top">here</a> 
     for details.</P>
      
   <H3><A name="Reuse_Graph"></A> Reuse Graph </H3>
      
     <P> If checked, the same graph window will be used to display all BSim feature graphs.  Only 
     one feature graph is displayed at a time (the previous feature graph will be cleared).  If 
     unchecked, each feature graph will be drawn in a separate window. Note that in either case only
     one feature at a time will be highlighted in the decompiler. </P>
      
   <H3><A name="Decompiler_Timeout"></A> Decompiler Timeout </H3>
      
     <P> This parameter controls the maximum amount of time (in seconds) the decompiler will spend 
     trying to decompile a function before quitting. </P>
     
   <H3><A name="Highlight_By_Row"></A> Highlight by Row </H3>
   
     <P> If selected, the decompiler highlights will be applied whenever the selected row in the
     BSim Feature Table changes. </P>
      
</BODY>
</HTML>
